﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML dir=ltr XMLNS:MSHelp = "http://msdn.microsoft.com/mshelp" xmlns:ddue = 
"http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink = 
"http://www.w3.org/1999/xlink" xmlns:tool = "http://www.microsoft.com/tooltip" 
XMLNS:[default] http://ddue.schemas.microsoft.com/authoring/2003/5 = 
"http://ddue.schemas.microsoft.com/authoring/2003/5"><HEAD><TITLE>Message Buffer Sample</TITLE>
<META content="text/html; CHARSET=utf-8" http-equiv=Content-Type></META>
<META name=save content=history></META>
<LINK rel=stylesheet type=text/css 
href="../../../../CommonFiles/Classic.css"></LINK>

<META name=GENERATOR content="MSHTML 8.00.6001.18783">
<style type="text/css">
.style2 {
				font-size: 90%;
}
</style>
</HEAD>
<BODY><INPUT id=userDataCache class=userDataStyle type=hidden></INPUT><INPUT 
id=hiddenScrollOffset type=hidden></INPUT><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=dropDownImage 
src="../../../../../Common/Html/drpdown.gif"></IMG><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=dropDownHoverImage 
src="../../../../../Common/Html/drpdown_orange.gif"></IMG><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=copyImage 
src="../../../../../Common/Html/copycode.gif"></IMG><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=copyHoverImage 
src="../../../../../Common/Html/copycodeHighlight.gif"></IMG><DIV id=header>
<TABLE id=topTable width="100%">
  <TBODY>
  <TR id=headerTableRow1>
    <TD align=left><SPAN id=runningHeaderText></SPAN></TD></TR>
  <TR id=headerTableRow2>
    <TD align=left><SPAN id=nsrTitle>Message Buffer PlainHttp 
  Sample</SPAN></TD></TR>
  <TR id=headerTableRow3>
    <TD></TD></TR></TBODY></TABLE>
</DIV>
<DIV id=mainSection>
<DIV id=mainBody>
<DIV id=allHistory class=saveHistory onload="loadAll()" 
onsave="saveAll()"></DIV>
<P>Message Buffers are small, temporary message caches that enable “Web 
programming model” scenarios. Such situations arise when you cannot use an Service 
Bus binding to create a message consumer. This scenario can arise if your consumer is written in Java, 
or if it is running 
on a non-Windows computer or on a mobile device. In this scenario, the message 
consumer uses Http calls to poll for messages, and the message buffer provides a 
place where messages sit for a short time until the polling 
request picks them up.</P>
<P>This sample demonstrates how to program the message buffer using its REST 
protocol. The message buffer protocol is an HTTP REST-based API that is designed 
to follow common REST principles. As such, you can easily leverage the protocol 
from any client without requiring the Windows Azure SDK. The 
protocol relies on the ACS HTTP authentication model to help enforce access 
control on the message buffer. Specifically, it uses the Simple Web Token (SWT) 
mechanism to retrieve a token using HTTP, then embeds it in an HTTP request 
as a header. This token includes claims that are used to determine whether or 
not an operation should be allowed. </P>
<P>Each message buffer has a unique URI in the Service Bus namespace. 
This URI is the "root" for a set of resources that represent the message buffer 
"instance." Each resource, in turn, has a unique URI and can be acted upon by a set of 
HTTP verbs. The URIs are organized in a way that helps convey the logical 
relationships between the different types of resources.</P>
<P>The verbs which act upon resources are modeled upon the standard HTTP verbs.</P>
<UL>
  <LI class=unordered>PUT: Creates a new resource or updates an existing 
	resource.<LI class=unordered>
	POST: Updates an existing resource.<BR>
  <LI class=unordered>DELETE: Deletes an existing resource.<BR>
  <LI class=unordered>GET: Retrieves a representation of a resource.</LI>
</UL>
<p>In Windows Azure, POST is used to send credentials to the Access Control 
service to retrieve a WRAP token, and to send a message to the message 
buffer. PUT is used to create a new message buffer or to update the 
policy of an existing message buffer.</p>
<p>The following section lists common operations that can be performed on the 
message buffers using the REST protocol.</p>
<H2 class=heading>Request a WRAP token from ACS</H2>
<DIV id=sectionSection0 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<P xmlns="">To interact with the Message Buffer, you must get a token from the 
appropriate Service Bus issuer.</P>
<H3 class=subHeading xmlns=""></H3>
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>
		<a href="https://{service-namespace}-sb.accesscontrol.windows.net/">https://{service-namespace}-sb.accesscontrol.windows.net</a>/ </P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>POST</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>None</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body (encrypted)</P></TD>
    <TD>
      <P>wrap_name={issuer name}&amp;wrap_password={issuer key}&amp;applies_to=http://{service-namespace}.servicebus.windows.net/{message-buffer-name}</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>wrap_access_token={token}&amp;wrap_access_token_expires_in={token-expiry-time}</P></TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>Create a new Message Buffer or update an existing one&#39;s policy</H2>
<DIV id=sectionSection1 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>
		<a href="https://{service-namespace}.servicebus.windows.net/{message-buffer-name">https://{service-namespace}.servicebus.windows.net/{message-buffer-name</a>} 
		(http is valid too)</P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>PUT</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P>
		<P>Content-Type: 
      application/atom+xml;type=entry;charset=utf-8</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>{policy-xml} (Please refer the &quot;Message Buffer policy schema&quot; section 
		in this document)</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>{policy-xml} (policy properties will be assigned their default values 
		if their values in the request are absent or invalid)</P></TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>Delete a Message Buffer</H2>
<DIV id=sectionSection2 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>
		<a href="https://{service-namespace}.servicebus.windows.net/{message-buffer-name">https://{service-namespace}.servicebus.windows.net/{message-buffer-name</a>} </P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>DELETE</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>Get a Message Buffer&#39;s policy</H2>
<DIV id=sectionSection9 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>
		<a href="https://{service-namespace}.servicebus.windows.net/{message-buffer-name">https://{service-namespace}.servicebus.windows.net/{message-buffer-name</a>}</P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>GET</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>{policy-xml}</P></TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>&nbsp;</H2>
<H2 class=heading>Send a message to the Message Buffer</H2>
<DIV id=sectionSection3 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>
		<a href="https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages">https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages</a></P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>POST</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P>
		<P>Content-Type: 
      application/atom+xml;type=entry;charset=utf-8</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>{message-payload}</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>
		(Empty)</P>
	</TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>Retrieve a message in the Message Buffer (destructive 
read)</H2>
<DIV id=sectionSection4 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/head?timeout={timeout-in-seconds}</P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>DELETE</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>{message-payload}</P></TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>Lock a message in the Message Buffer (non-destructive 
read)</H2>
<DIV id=sectionSection5 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/head?timeout={timeout-in-seconds}&amp;lockduration={lockduration-in-secs}</P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>POST</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR>
  <TR>
    <TD>
      <P>Response Headers</P></TD>
    <TD>
      <P>X-MS-MESSAGE-LOCATION: 
      <a href="https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id">https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id</a>}</P>
		<P>X-MS-LOCK-ID: 
      {lock-id}</P>
		<P>X-MS-LOCK-LOCATION: 
      https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}/{lock-id}</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>{message-payload}</P></TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>Unlock a locked message in the Message Buffer</H2>
<DIV id=sectionSection6 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}/{lock-id}</P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>DELETE</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR></TBODY></TABLE></content></DIV>
<H2 class=heading>Delete a locked message from the Message Buffer</H2>
<DIV id=sectionSection7 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Resource URI</P></TD>
    <TD>
      <P>https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}?lockid={lock-id}</P></TD></TR>
  <TR>
    <TD>
      <P>HTTP Verb</P></TD>
    <TD>
      <P>DELETE</P></TD></TR>
  <TR>
    <TD>
      <P>Request Headers</P></TD>
    <TD>
      <P>Authorization: WRAP access_token=&quot;{token}&quot;</P></TD></TR>
  <TR>
    <TD>
      <P>Request Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR>
  <TR>
    <TD>
      <P>Response Body</P></TD>
    <TD>
      <P>(Empty)</P></TD></TR></TBODY></TABLE></content></DIV><!--[if gte IE 5]><tool:tip 
avoidmouse="false" element="languageFilterToolTip"></tool:tip><![endif]--></DIV>
<DIV id=mainBody0>
<H2 class=heading>&nbsp;Message Buffer policy XML schema</H2>
<DIV class=code xmlns=""><SPAN codeLanguage="xml">
<TABLE cellSpacing=0 cellPadding=0 width="100%">
  <TBODY>
  <TR>
    <TH>Xml&nbsp;</TH>
</TR>
  <TR>
    <TD colSpan=2><PRE>&lt;entry xmlns="http://www.w3.org/2005/Atom"&gt;&lt;content type="text/xml"&gt;
&lt;MessageBufferPolicy xmlns="http://schemas.microsoft.com/netservices/2009/05/servicebus/connect"&gt;
    &lt;Authorization&gt;{AuthorizationPolicy}&lt;/Authorization&gt;
    &lt;Discoverability&gt;{DiscoverabilityPolicy}&lt;/Discoverability&gt;
    &lt;TransportProtection&gt;{TransportProtectionPolicy}&lt;/TransportProtection&gt;
    &lt;ExpiresAfter&gt;hh:mm:ss&lt;/ExpiresAfter&gt;
    &lt;MaxMessageCount&gt;nnn&lt;/MaxMessageCount&gt;
    &lt;OverflowPolicy&gt;{OverflowPolicy}&lt;/OverflowPolicy&gt;
&lt;/MessageBufferPolicy&gt;
&lt;/content&gt;
&lt;/entry&gt;</PRE></TD></TR></TBODY></TABLE></span></div>
<span class="style2"><br>
The various property values are as follows:<br>
<br>
<DIV id=sectionSection10 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<TABLE xmlns="">
  <TBODY>
  <TR>
    <TD>
      <P>Authorization Policy</P></TD>
    <TD>
      <P>NotRequired, Required, RequiredToReceive, OR RequiredToSend</P></TD></TR>
  <TR>
    <TD>
      <P>Discoverability Policy</P></TD>
    <TD>
      <P>Managers, ManagersListeners, ManagersListenersSenders, OR Public</P></TD></TR>
  <TR>
    <TD>
      <P>Transport Protection Policy</P></TD>
    <TD>
      <P>None OR AllPaths</P></TD></TR>
  <TR>
    <TD>
      <P>Expires After</P></TD>
    <TD>
      <P>hh:mm:ss</P></TD></TR>
  <TR>
    <TD>
      <P>Max Message Count</P></TD>
    <TD>
      nnn</TD></TR>
  <TR>
    <TD>
      Overflow Policy</TD>
    <TD>
      RejectIncomingMessage</TD></TR></TBODY></TABLE></content></DIV><br>
</span>
    <hr /> 
    <h2 class="heading">
        Building and Running the Sample</h2>
    <div id="sectionSection11" class="section">
        <content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
        <p xmlns="">
            After building the solution, do the following to run the application:
        </p>
        <ol class="ordered" xmlns="">
            <li>From a command prompt, run the service application from bin\Debug\PlainHttp.exe.<br />
                <br />
            </li>
            <li>When prompted, enter the service namespace, issuer name and the issuer key.
                <br />
                <br />
            </li>
            <li>The sample will create a message buffer, retrieve a message from it and delete 
                the message buffer.
                <br />
                <br />
            </li>
        </ol>
        </content>
    </div>
    <br />
    <br />
    Did you find this information useful?
     <a href="http://go.microsoft.com/fwlink/?LinkID=155664">
        Please send your suggestions and comments about the documentation.

    </a></P></DIV></BODY></HTML>
